Summary

Splits blog article rendering out of the monolithic MdxRoute into a dedicated BlogArticleRoute, and introduces reusable infrastructure (MdxFile, MdxContent, CompiledMdx) that paves the way for splitting out the remaining routes (docs, community, syntax-lookup) and eventually removing react-router-mdx.

Motivation

MdxRoute.res handles every MDX-backed page on the site — blog posts, docs, community pages, and syntax lookup — in a single loader and a long chain of if/else branches. This makes it hard to reason about, test, and modify individual sections without risk of breaking others. Blog is the simplest case and a good first candidate to extract.

What changed

New files

Modified files

How MDX rendering works

The blog route uses the same MDX pipeline as react-router-mdx but with our own code, which will make it possible to remove that dependency later:

Server (loader):

Raw .mdx file on disk
  → Node.Fs.readFile
  → MdxFile.compileMdx (calls @mdx-js/mdx compile with outputFormat: "function-body")

Client (component):

CompiledMdx.t (opaque compiled string from loader data)
  → MdxContent evaluates with runSync + react/jsx-runtime
  → Renders with shared component map (CodeTab, Info, Warn, etc.)

This means custom MDX components like <CodeTab labels={["RE", "JS"]}> work correctly — unlike the earlier approach of passing raw markdown to react-markdown, which can't handle JSX expressions in attributes.

Key design decisions

• CompiledMdx.t is opaque — the .resi exposes only type t and fromCompileResult. You can't accidentally pass a random string where compiled MDX is expected.
• MdxContent owns the component map — since the same components are used across all MDX pages on the site, they live in one place rather than being duplicated in each route.
• No %raw — MdxContent uses proper @module bindings to react/jsx-runtime and @mdx-js/mdx instead of raw JS. The jsx-runtime exports are imported as opaque jsxRuntimeValue types to sidestep ReScript's monomorphisation of the polymorphic React.jsx/React.jsxs signatures.
• MdxFile.compileMdx calls @mdx-js/mdx compile directly, making react-router-mdx no longer needed for blog routes. The remaining routes still use it for now.